Code Reading
目的にも依るが、できるだけ高速に構造を頭に入れるのが良さそうだろう
その対象のコードに対するメンタルモデルを自分の中に構築する
そのためには、コードを読む以外で情報を集めた方が有効な可能性もある
ドキュメント上でmodule構成の話などをしていたり、PR上にそういう議論をしていたり、既に読んだことのある人のログがあるならそっちを先に読んだほうが速い
そういう情報がないなら、仕方なく実際にコードを読んでいくことになる
抽象的な部分から読んでいく
そのために、色々支援ツールが必要になる
ディレクトリ構造を見る
特定のファイルを開かずに、ファイルツリーだけ見て目的が達成できたら最高だろう
moduleの繋がりを見る
可視化するツールが必要だろう
その大きな概念がどういうパーツで構成されていそうかを予想しながら見る
各ディレクトリやmoduleのボリュームを見る
ボリュームが大きいものがそのリポジトリの根幹を担っているものだろう
エントリファイルから読む
コメントを読む
関数名と型だけを読む
test codeをよむ
詳細をテストしていない良いテストなら、インターフェースだけで必要十分なものを伝えているはず
ChatGPTに読ませる
いかにして具体的な部分を読まないかが重要になってくる
こういうのは自分でコードを書くときも同じ
いかにして詳細を読まずとも、内容を伝えられるか、というのを意識して書く
そういう意味で、手続き的なコードや、状態を扱っているOOPはかなり読みづらい
手続きを追わないと理解ができない
どうしても具体的なところを見ないといけなくなる
これを支援するツールを作るとすると、
CLIコマンドでどうのこうのというよりは、エディタの拡張として作ったほうが良さそう
普段のコーディングの延長で気軽に実行できるべき
なにか別のリポジトリを落としてきて読んでいくこともあるが、他のチームメンバが書いた部分を読むこともあるわけだし
逆に、自分が書いたコードに対し、ツールを適用することで、わかりやすいコードになっているかどうかを自分で評価できると良い
最初にやりたいこと
全体像を知る
アーキテクチャを知る
これをやらないと、読みたい対象がどこにあるのかがわからない
ディレクトリ構造から類推する
型を理解する
スコープが、大きめにも、小さめにも
これができるかどうかは、コードリーティングしたい対象の良さに依存する
型駆動で開発されているとかなり理解しやすい
参考
プログラマー脳
サクッと読んでるときはさほどだったが、code readingに悩んでいるタイミングで読むとなにかヒントがあるかも
ChatGPTに聞く
コードをコピペしても良いし、GitHubのURLを投げて読んでもらっても良い
GitLensの機能はもっとどしどし使っていったほうが良さそうmrsekut.icon GitHub repoをサクッとコードリーディングする
ワーキングメモリに過負荷をかけるパターン
コードのどの部分を読めばよいかわからない
無駄に詳細に読んでしまう
詳細に読むか流れを読むかの決定に迷う
ある関数Aを読んでる時に、知らない関数Bが使われているのを発見した時に、
そのままAを読み続けるか、
いったんBに入り込むか
を迷ってしまう
依存関係グラフを作成する
印刷して、変数に丸をつけて、同じものを結ぶ
視覚的に見ようねという感じ
状態遷移表を書く
JSとかも使える
テキスト構造の理解
ミクロ
変数の役割を考えるとか
計画の理解
マクロ
この関数が書かれた目的を考える
やりたいこと、欲しいツール
読んでる最中にアノテーションメモを残したい
1ファイルが大きい時に邪魔な関数等を非表示にしたい
VSCodeならcmd-alt-[などで折り畳めるが、そういう次元の話ではなく
さっそくコードを読むのではなくファイルツリーから概要を掴む
各featureのコードの行数を算出する
どこが複雑なのか、コアなのか、重要なのか、といった判断ができる
名前などから類推しながら、中を軽く読んでいく
このノートに限らず、このプロジェクト内にいろいろ知見がある
可視化する
vscode拡張
コードを汚さずにメモを取れる
入れてないmrsekut.icon
コアの部分から読む(mainとか)
プログラムがどのように動いているか考えながら読む。
ソースコードの半分以上はオプションが指定されたときの処理か、エラーが発せいたときの処理。
最初は「オプション処理してるな」位の感覚でそれ以上深入りしない。
こういうプログラムならこういう手順で行われているだろう」といった、大まかな流れがわかっていると良い。
そうすると、関数名を読むだけでも、だいたい何やっているかわかったりする。
とりあえず全部流し見する。
どんな関数やクラスがあるのか、この作者はどのような感じのプログラムを書くのかなどの傾向を把握する
コメントは読みましょう
速く読もうと意識して読むのが良い.
速く読もうとしなければ速く読めるようにはならない
読むときに仮設と検証を行う
コードにコメントを追加する
コメントを追加しながら読む
理解とともにコメントは増やしていく
アノテーションコメントを残す
解決すべき課題、確認すべき仕様、改善すべき箇所などは # TODO: など、アノテーションコメントを残す
ファイル配置を手がかりにする
ソフトウェアの種類によっては、典型的なファイル配置が決まっていることがある
なのでそのディレクトリ構成やファイル名を辿ることで全体像をつかむことができる
メソッドの最終行に注目する
オブジェクト指向のプログラムは、メソッドの前半に実行に必要な変数などの下処理を行い、
後半に実際に実行処理を行うケースが多いから。
動的な解析
デバッガなどを使って実行時の動きを追う
静的な解析
ドキュメントを読む
'hacking','tour'などのキーワードがあれば要チェック
ディレクトリ構造を読む
ファイル構成を読む
ファイル中の関数名も合わせて、どの程度の単位でファイル分割されているかを確認
関数の命名などもチェック
略語の調査
関数同士の呼び出し関係
関数が多い場合は特に重要
図に書く
関数を読む
mainのようなルートっぽいところからたどっていく
「なにを読まないか」をよく考える
書き換えて動かす
Nimのparserを読んでて思ったこと
巨大な(2000行ほど)のコードをコアな部分を写経しながら、もっとシンプルなものを作ってみようとすると、理解しやすいと感じた コードを読むときは目標を決めて重点的に読もう
新しいコーディングスタイルを学ぶのか？
何かの要件を満たす方法を知りたいのか？
etc
関数
名前から機能を推測する
関数の冒頭に書かれているコメントを読む
関数の使われ方を調べる
本体のコードを読む
関連ドキュメントを調べる
コードリーディングハンズオン
その目的のコードが今もメンテされているかは少し注目
メンテされていれば、動くことが保証される
最低限必要なもの
「ファイル名」から中身を予想する勘と経験
Go to Definition
その言語の基礎文法
その他思ったこと
クラスの継承が多く見られるときはgraphvizなどで図示しておくと良さそう
追加したいものを周りのコードを見比べながら進めるので、したいことによっては0から作るよりずっと簡単
クラスや関数の呼び出しがスタックされる場合も図示しておくと良さそう
プロジェクトを作っている組織へ途中から入りちょっとずつ知っていくあの感じにすごく似てた
関連
コードの読み方、動的、静的な解析ツールの詳解
DBの設計を把握しよう
mizchi氏のコードリーディングメモ
途中からプロジェクトに参加するとき